# 游戏主屏幕脚本
# 该脚本负责管理游戏主屏幕的逻辑，包括加载和显示当前地图
# 作为游戏运行时的主要容器，它会根据GameManager中的当前地图路径加载对应的地图场景
#
# 继承自Node类，可以访问Node的所有属性和方法:
# 重要属性:
# - name: 节点名称，用于在场景树中标识该节点
# - visible: 可见性，控制节点及其子节点是否可见
# - process_mode: 处理模式，决定何时调用_process和_physics_process方法
#
# 重要方法:
# - add_child(): 添加子节点到当前节点
# - remove_child(): 从当前节点移除子节点
# - get_node(): 根据路径获取场景树中的节点
# - queue_free(): 安全地计划删除节点
#
# 重要信号:
# - ready: 节点准备就绪时触发
# - tree_entered: 节点进入场景树时触发
# - tree_exiting: 节点退出场景树时触发

extends Node

class_name GameScreen

# 导出map节点，允许在编辑器中指定地图容器节点
# 通过在编辑器中导出该属性，可以在Inspector面板中直接分配节点引用
# 这样可以灵活地指定地图容器，而不需要硬编码节点路径
@export var map: Node

# Called when the node enters the scene tree for the first time.
# 当节点首次进入场景树时调用
# 这是节点初始化的关键方法，在此执行一次性设置操作
func _ready() -> void:
	# 按照实际执行顺序的详细说明:
	# 1. load(GameManager.currentMapPath) - 加载指定路径的地图场景资源
	#    - 从GameManager获取当前地图路径
	#    - 使用ResourceLoader.load()加载该路径的资源
	#    - 返回的是PackedScene类型的资源对象（还未成为场景树中的节点）
	#
	# 2. instantiate() - 实例化加载的场景资源
	#    - PackedScene.instantiate()将资源转换为实际的节点树
	#    - 返回的是场景的根节点实例，可以被添加到场景树中
	#    - 此时节点还不存在于场景树中，只是在内存中创建了节点实例
	#
	# 3. map.add_child() - 将实例化的节点添加到map节点中
	#    - 将实例化的地图节点作为子节点添加到map节点
	#    - 只有在这一步之后，节点才真正成为场景树的一部分并开始运行
	#    - 成为场景树一部分的节点会开始接收各种回调，如 _ready(), _process() 等
	# 为什么要先实例化再添加:
	# - PackedScene是存储场景结构的资源，不是实际的节点
	# - 必须先调用instantiate()将资源转换为实际的节点实例
	# - 只有节点才能被添加到场景树中，资源不能直接添加到场景树
	# - add_child()只能接受Node类型的参数，不能接受PackedScene类型的参数
	
	map.add_child(load(GameManager.currentMapPath).instantiate())
